fix(server): refuse to start a second server against a live data directory - #8442

What Changed

A new apps/server/src/serverSingleton.ts claims the data directory at server startup. A second server started against a directory another live server already holds now exits 1 with an explanatory message instead of starting anyway.

The lock is Layer.provided into HttpServerLive rather than merged beside it, so the ordering is structural rather than incidental: the lock is a dependency of the thing it protects, and no server reaches a listening socket while another holds the directory.

Three files, no refactors, no behaviour change for the single-server case. Only t3 serve and t3 start build the server layer, so no other subcommand is affected.

Why

Two T3 Code servers pointed at the same --base-dir both open state.sqlite and both write settings.json, and they overwrite each other. Nothing refuses the second start, and nothing reports it afterwards.

The port check does not save you. When :3775 is already taken, the second server binds a different port and starts normally — so it looks perfectly healthy while running blind against shared state.

Repro:

# terminal 1
t3 serve --base-dir /tmp/t3-repro --port 39977

# terminal 2 — same data directory, different port
t3 serve --base-dir /tmp/t3-repro --port 39978

Before this change both start. Both hold /tmp/t3-repro/userdata/state.sqlite open and both write /tmp/t3-repro/userdata/settings.json; whichever writes last wins, and the other UI silently reverts.

How I hit it in the wild: a desktop app auto-updated to a newer server while the old one was still running. The server does not self-upgrade, so npx t3@<newer> started a second server against the same data directory. The visible symptom was a settings toggle that would not stick — about an hour away from the actual cause, and nothing about it is detectable after the fact.

After this change, the second server exits 1 without binding a port:

Another T3 Code server is already using this data directory.

  data directory: /tmp/t3-repro/userdata
  held by:        pid 285163, listening on port 39977
  since:          2026-08-27T16:59:03.329Z

Two servers sharing one data directory overwrite each other's state.sqlite
and settings.json. Stop the running server, or start this one with a
different --base-dir.

If that process is gone, remove /tmp/t3-repro/userdata/server.lock and start again.

Why a pid file and not flock

An advisory flock is the better primitive — the kernel drops it when the holder dies, so a crash leaves nothing stale. Node has no binding for it, and pulling in a native dependency for one lock seemed the worse trade. So this is a file created atomically with wx holding the owner's identity, with liveness checked via signal 0 (treating EPERM as alive, since a server running as another user must not be trampled).

The tradeoff is stated in the module rather than hidden: a server that is killed and whose pid is later reused by an unrelated process will block startup until the lock file is removed. That is the safe direction to fail, and the message names the file so recovery is one rm. If you would rather take the native dependency and use a real flock, say so and I will redo it that way.

Staleness is handled rather than fatal: a lock whose owner is gone, or which a crash tore in half mid-write, is reclaimed. Reclaiming re-races the exclusive create, so two servers starting simultaneously still produce exactly one winner. Release only removes a lock this process still owns, so a successor is never evicted by its predecessor's shutdown.

The bound port is stamped onto the lock after binding, purely so a later refusal can name an address the user can open rather than a bare pid.

One thing worth flagging for review: the lock is structurally guaranteed to precede the HTTP server binding, which is what the refusal path depends on. I did not attempt to order it against every sibling layer, so I would not claim it strictly precedes the first SQLite open in all compositions.

UI Changes

None — server startup behaviour only.

Tests

apps/server/src/serverSingleton.test.ts — 9 tests, following the existing it.layer(NodeServices.layer) convention used elsewhere in this directory: claim/release on scope exit, refusal while held, stale-pid reclaim, half-written-file reclaim, successor not evicted on release, port recorded and surfaced in the refusal, separate directories independent, and pid liveness.

I checked the tests actually bite rather than just passing: changing the exclusive create from { flag: "wx" } to { flag: "w" } fails "refuses a second server while the first holds the directory" and "records the bound port so the next server can name it".

Verified locally:

• vp test run src/serverSingleton.test.ts → 9 passed
• full apps/server suite → 246 files passed, 2824 passed / 10 skipped (baseline on this commit's parent: 245 files, 2815 passed)
• vp run typecheck → exit 0
• vp fmt --check → clean; vp lint reports nothing new for the changed files

Also verified end to end with two real server processes against one --base-dir: the second refuses, exits 1, and never binds; SIGKILLing the holder leaves a stale lock that the next start reclaims; ordinary shutdown releases the lock and a restart is unblocked.

Checklist

• This PR is small and focused
• I explained what changed and why
• I included before/after screenshots for any UI changes (n/a — no UI change)
• I included a video for animation/interaction changes (n/a)